feat(csharp): XML encode contents of <summary> and <example><code> code comments #4785
Conversation
Swimburger
changed the title
| @@ -11,7 +11,7 @@ public record User | |||
| public required string Id { get; set; } | |||
|
|
|||
| /// <summary> | |||
| /// The user's name. This name is unique to each user. A few examples are included below: | |||
| /// The user's name. This name is unique to each user. A few examples are included below: | |||
There was a problem hiding this comment.
it's looking like lodash's escape might be a little overkill for us -- from my understanding, lodash is going to escape the following chars: & < > " '
But I think that we only need carats to be escaped
Can we roll our own method that only escapes carats?
There was a problem hiding this comment.
Yes, I was on the fence about that. Let's do it ourselves.
There was a problem hiding this comment.
@dcb6 The code has been updated with our own escaping.
…l-encode-csharp-comments
| }); | ||
| writer.writeLine("/// </code>"); | ||
| writer.writeLine("/// </example>"); | ||
| writer |
There was a problem hiding this comment.
The DocXmlWriter is awesome!
and overall i like the ideas that you're bringing here, such as this fluent writer API, but i'd prefer consistency with our existing writer. I'd also like to avoid adding new write methods to our existing writer. So, I have a couple changes to propose:
- remove the
writeDocXmlmethod from theWriterclass and instead just initialize aDocXmlWriterhere (and elsewhere) - remove the fluent elements of the
DocXmlWriterby simply have the methods returnvoid, and changing the usages accordingly
I ack this is fairly opinionated, but I think we consider it more important to adhere to a consistent style than to introduce new patterns that bring fairly slight improvements
|
This part of the description is no longer accurate, correct?
|
Correct! |
When
<and>are used inside of summary or code example XML docs, the XML doc is invalid.This PR HTML encodes the contents before putting it in the XML doc.
This will also XML encode other characters which aren't really necessary, like", but IDEs continue to show the XML docs correctly.